3.1 The should Macro

Test bodies can include arbitrary code; but to be useful, they need to check whether the code being tested (or code under test) does what it is supposed to do. The macro should is similar to cl-assert from the cl package (see Assertions in Common Lisp Extensions), but analyzes its argument form and records information that ERT can display to help debugging.

This test definition

(ert-deftest addition-test ()
  (should (= (+ 1 2) 4)))

will produce this output when run via M-x ert:

F addition-test
    (ert-test-failed
     ((should
       (=
        (+ 1 2)
        4))
      :form
      (= 3 4)
      :value nil))

In this example, should recorded the fact that (= (+ 1 2) 4) reduced to (= 3 4) before it reduced to nil. When debugging why the test failed, it helps to know that the function + returned 3 here. ERT records the return value for any predicate called directly within should.

In addition to should, ERT provides should-not, which checks that the predicate returns nil, and should-error, which checks that the form called within it signals an error. An example use of should-error:

(ert-deftest test-divide-by-zero ()
  (should-error (/ 1 0)
                :type 'arith-error))

This checks that dividing one by zero signals an error of type arith-error. The :type argument to should-error is optional; if absent, any type of error is accepted. should-error returns an error description of the error that was signaled, to allow additional checks to be made. The error description has the format (ERROR-SYMBOL . DATA).

There is no should-not-error macro since tests that signal an error fail anyway, so should-not-error is effectively the default.

See Understanding Explanations, for more details on what should reports.